ParcelAddress API
ParcelAddress Overview
Overview
The ParcelAddress API is a GET API that contains methods that return valid matching domestic or international addresses. You can use the returned results to display a subset of the matching addresses so that the user can select the intended address instead of needing to type in the entire address. Once a specific address is selected, the Get Address Details methods can be called to retrieve a complete set of the address detail.
ParcelAddress includes the following resources:
| Name | Function | Verb | Resource |
|---|---|---|---|
| Search for an International Address | Retrieve international addresses matching provided address fragment and country code | GET | /international/addresses |
| Get International Address Detail | Retrieve international address detail for provided identifier | GET | /international/addresses/{address_id} |
| Search for an Address | Retrieve domestic addresses matching provided address fragment | GET | /domestic/addresses |
| Get Address Detail | Retrieve domestic address detail for provided AddressID | GET | /domestic/addresses/{address_id} |
| Get Address Detail | Retrieve domestic address detail for provided dpid | GET | /domestic/addresses/dpid/{dpid} |
| Australian Address Lookup | Retrieves Australian Address detail and returns in NZ Post format | GET | /australia/addresses/{address_id} |
| Collection Locations | Retrieves the closest collection points to the coordinates provided | GET | /domestic/pcdlocations |
| Domestic Suburbs Suggestion | Retrieve domestic suburbs matching provided suburb fragment | GET | /domestic/suburbs |
Operational Considerations
The following information is intended to inform integrating merchants of NZ Post Group operational processes that may impact how the ParcelAddress API is used.
- When designing your application, please consider the user experience should the ParcelAddress API be unavailable. Recommendation: The integrating applications should allow manual entry of the address if the ParcelAddress API becomes unavailable. Manually entered addresses should be validated to ensure that they include either suburb and post code or town and postcode or DPID or Address ID.
- Note that the ParcelAddress API provides two address search services, one for New Zealand addresses and one for international addresses. If you expect your application to be used for searching for addresses both in New Zealand and overseas, your user interface should capture the country prior to the street address so that your application's logic can determine which service to invoke.
- Because international address look up uses the country to define the search, the country must correspond to a known list of countries. Recommendation: Provide your customers with a pick list of countries to choose from that matches the list of accepted countries. A list of valid country codes can be found here.
- Fields and validation must allow for three types of address entry, Street Address, P.O Box and Private Bag.
- The NZ Post ParcelAddress API is only to be used for customers capturing address data for the purpose of producing accurate address labels for NZ Post, Pace or CourierPost services. If the API is being accessed but the account is not producing corresponding parcel labels, access to the API may be revoked (refer to the Specific Terms in section Terms and Conditions).
- If a collection point is selected as the delivery address, and the merchant is using the ParcelLabel API, the merchant must populate the "collection" flag in the label request so that the label is generated correctly.
- If the delivery address that is used for labeling is an NZ Post collection point then you MUST create a PCD type subscription for the parcel recipient via the ParcelNotification API. This requires the tracking reference from the label, parcel recipient's first and last names, email address and the location ID of the collection point.
- The Domestic Suburbs Suggestion resource is provided to enable end users to select a valid suburb, after they have entered a street address that could not be validated. If for any reason the system is unable to return a valid suburb (source system down), then the user must be able to manually enter the suburb and post code.